Inside Macintosh: Programming With JManager /

Chapter 1 - Using JManager

Finding Applets

Before you can instantiate and execute your applet, you must find the applet code by creating a JMAppletLocatorRef object. You can create such an object either synchronously or asynchronously. A synchronous search assumes that the applet's location can be immediately verified (for example, it is contained in a local file). You use the JMNewAppletLocatorFromInfo function (page 70) for a synchronous search, and you must provide information about the location of the applet in a JMLocatorInfoBlock data structure. The location information is the same as you would find in an applet tag in an HTML document. Listing 1-3 shows an example of using JMNewAppletLocatorFromInfo.

Listing 1-3 Using the JMNewAppletLocatorFromInfo function

OSStatus err = noErr;
JMAppletLocatorRef locatorRef;

JMLocatorInfoBlock infoBlock = {
   kJMVersion,                   /* should be kJMVersion */
   "file:///$APPLICATION/applets/DrawTest/example1.html",
   "DrawTest.class",             /* from the applet tag */
   400, 400,                     /* width, height */
   0, nil         /* no optional parameters in this example */
};

/* create the locator */ 
/* If noErr is returned, the infoBlock was valid */
err =  JMNewAppletLocatorFromInfo(&locatorRef, 
      theSession, &infoBlock, 0);

if (err == noErr) {
   /* instantiate and execute applet */
   }

The /$APPLICATION/ indicator in the URL is an Apple-specific designation that indicates the current application directory.

For more information about the JMLocatorInfoBlock structure, see "The Applet Locator Information Block" (page 49).

If the applet is located on a remote server, you should search for it asynchronously using the JMNewAppletLocator function (page 70). Listing 1-4 shows an example of using JMNewAppletLocator.

Listing 1-4 Using the JMNewAppletLocator function

JMAppletLocatorRef locatorRef;
struct JMAppletLocatorCallbacks locatorCallbacks = {
   kJMVersion,         /* should be kJMVersion */
   MyFetchCompleted    /* called on completion */
   };

static const char kSampleURL[] = "http://www.hypno.com/javabeta/bongo/
   bongo.html";

/* ignore the result--no pointer is passed to the */
/* html text, since it might not exist locally.*/
(void) JMNewAppletLocator(&locatorRef, theSession,
          &locatorCallbacks, kSampleURL, nil, 0);

/* this is the callback function specified in locatorCallbacks */
static void MyFetchCompleted(JMAppletLocatorRef locatorRef,
      JMLocatorErrors status){
   if (status != eLocatorNoErr) {
      /* handle the error here--perhaps put up a dialog box */
      } 
   else {
      /* instantiate and execute applet */
      }
}

In the asynchronous search, you pass HTML text indicating the location of the applet and specify a callback function to execute when the search is completed. The callback function can take various actions depending on the status value returned. For more information about the callback function, see MyFetchCompleted (page 106).

One you have found your applet's location, you should call the JMCountApplets function (page 73) to determine the number of applets associated with the HTML page. JMCountApplets counts the number of applets and assigns an index value to each. Then you can use the functions JMGetAppletDimensions (page 74), JMGetAppletTag (page 75), and JMGetAppletName (page 76) to determine which applet to instantiate or to get more information about a particular applet. Listing 1-5 shows an example that counts the number of applets and returns information about each.

Listing 1-5 Retrieving information from an applet's HTML page

UInt32 appletCount;
UInt32 appWidth, appHeight;
UInt32 i;
char appName[255];
/* iterate over the applets */
err = JMCountApplets(locatorRef, &appletCount);
printf("Number of Applets: "appletCount);

for (i = 0;  i < appletCount && err == noErr;  i++) {
   err = JMGetAppletName( locatorRef, i, &appName, 255) 
   if (!err) {
      err = JMGetAppletDimensions(locatorRef, i, &appWidth,
            &appHeight);
      if (!err) {
         printf("\nApplet #"i+1" is ";appName); 
         printf("Dimensions: "appWidth" by "appHeight" pixels");
         }
      }
   };

In some cases you might want to associate some client-specific data with an applet locator. To do so you can use the functions JMGetAppletLocatorData (page 72) and JMSetAppletLocatorData (page 73).

Both the JMNewAppletLocatorFromInfo and JMNewAppletLocator functions provide a valid JMLocatorRef object, which you can then use to instantiate and execute the applet. After instantiating the applet, however, you no longer need the JMLocatorRef object, so you can remove it by calling the JMDisposeAppletLocator function (page 72).